Tools Plus lets your application implement and support menus with considerably less effort than using the Macintosh toolbox’s routines. The fully automated Apple menu lets you launch, activate, and interact with desk accessories without having to write any code. Tools Plus also integrates the edit menu’s Undo, Cut, Copy, Paste, and Clear commands with editing fields, desk accessories and other applications so you don’t have to write any code to Cut, Copy, Paste, or Clear text, or to undo/redo your last operation.
There are two different kinds of menus your application can use, pull-down menus and hierarchical menus. When implementing menus, your application should adhere to Macintosh User Interface Guidelines as expressed throughout the series of Inside Macintosh manuals.
In this document, the term menu refers to the entire menu object; that is, [1] the entire pull-down menu and the name that appears in the menu bar, or [2] an entire hierarchical menu. The term menu item or item refers to individual items found within a menu. The item number is determined by counting from the top of the list, the first item being 1, the second being 2, etc.
Your application can create the Apple menu with the AppleMenu procedure. This procedure creates the Apple menu, inserts an optional “About…” item (first item) that is used to invoke your application’s “about box,” and populates the menu with a list of desk accessories.
A pull-down menu is created by the Menu procedure. First, your application specifies the menu’s name (which appears in the menu bar) and a menu number that can be from 1 to 15. The menu number refers to that specific menu until the menu is deleted. The Menu procedure is then used to add items to a specific menu.
A hierarchical menu is also created by using the Menu procedure. A name does not have to be specified for a hierarchical menu because this type of menu does not appear in the menu bar. Hierarchical menu numbers can be from 16 to 200. The menu number refers to that specific hierarchical menu until it is deleted. The Menu procedure is then used to add items to a specific hierarchical menu. You attach a hierarchical menu to an item in a pull-down menu or a hierarchical menu by using the AttachMenu procedure. When a hierarchical menu is attached to another menu, it is often called a submenu. In this relationship where a menu has one or more submenus, the owner of the submenus is often called the parent menu, and the submenus are sometimes referred to as offspring or child menus.
Menu items can also be inserted between others using the InsertMenuitem procedure. This lets your application maintain a dynamic menu that may be used, for example, for a list of open document names.
An entire menu can be deleted by using the RemoveMenu procedure. This procedure reclaims the memory used by the menu. Individual items can also be deleted using this procedure.
Menu items can be renamed by using the RenameItem procedure. This should be done judicially, since changes to menus and/or menu items may prove to be confusing to the user.
An entire menu can be enabled or disabled with the EnableMenu procedure, as can individual menu items. When an entire menu is disabled, it is dimmed along with all its associated items, and it cannot be selected. When an item is disabled, it becomes dim and cannot be selected.
After changes have been made to the menu bar by adding, deleting, enabling or disabling pull-down menus (not individual items), the UpdateMenuBar procedure should be called to display those changes on the menu bar.
Various other menu item-related features are supported, such as setting or removing “check marks” with the CheckMenu procedure. You can set or remove other marks with the MenuMark procedure, and determine which mark is displayed by using GetMenuMark. You can set and retrieve an item’s Command-key character with MenuCmd and GetMenuCmd. The same applies for icons that are displayed in menus, which are set and retrieved with MenuIcon and GetMenuIcon. An item’s text is retrieved with GetMenuString, and its style is set with MenuStyle.
Note: For the sake of consistency with other applications, your
application should have the following menus even if they are not
accessed:
• Apple menu
• File menu (first menu). The last item should be “Quit”
• Edit menu (second menu) with the standard items as defined
later is this chapter.
Menus Accessed by MultiFinder and System 7
``````````````````````````````````````````
This section describes how MultiFinder and System 7 automatically interact with your application’s menus if your application does not support high-level events (also called Apple Events). You should set the appropriate bit in your application’s ‘SIZE’ resource to indicate if it supports Apple Events or not. See the “Completing Your Application” chapter for details about the ‘SIZE’ resource.
Both MultiFinder (running under System 5 or 6) and System 7 can automatically interact with your application through its menus. If your application is running while the user double-clicks (or select-opens) one of your application’s documents from the Finder, the affected document is automatically opened by your application. Also, if the user selects the Special menu’s Restart or Shut Down command while your application is running, your application is instructed to quit.
In both these cases, the system simulates the selection of a menu item. You must have a File menu with an item named “Open…” (including the ellipsis, Option-; character), and the last item named “Quit”. In the case of opening a document, PollSystem returns a doMenu event to your application indicating that the File menu’s “Open…” command was selected, in which case your application would do whatever is appropriate, likely display an SFGetFile dialog to let the user choose which file to open. The system fools your application into thinking that the double-clicked file was selected from an SFGetFile dialog (which is not actually displayed). When the user selects Restart or Shut Down, PollSystem returns a doMenu event to your application indicating that the File menu’s “Quit” command was selected, in which case your application would do whatever is appropriate, such as asking if open documents should be saved before quitting.
If your application does not [1] open files by using the File menu’s “Open…” command, or [2] quit by using the File menu’s “Quit” command, see the chapter on “Completing Your Application,” where you can remap these functions to other menu items.
See the chapter on “Completing Your Application.” The section on “bundles” defines the association between your application and the files it creates, while the section on ‘mstr’ resources details remapping the ‘Open…’ and ‘Quit’ commands to other menu items.
Edit Menu
`````````
The Edit menu has a high degree of consistency across all Macintosh applications in appearance and function. Your application should have an Edit menu if your application:
• has two or more menus in the menu bar (excluding the Apple menu)
• uses editing fields
• supports desk accessories and runs under systems prior to System 7
It is good form to include an Edit menu in your application even if it doesn’t support its functions, just for the user’s familiarity.
Your application’s second menu must be called “Edit.” The Edit menu must contain the items “Undo”, “Cut”, “Copy”, “Paste” and “Clear” as the first five items in the listed order. A dividing line must exist between “Undo” and “Cut”. Tools Plus automatically enables and disables items in the Edit menu as described in the “Editing Fields” chapter under “The Edit Menu” whenever an editing field is active. It also automatically changes the “Undo” item to “Can’t Undo” when:
• a modeless window is created or closed
• an inactive window is activated
• an editing field is deactivated or activated (including selecting a
new editing field)
• a desk accessory performs a Cut or Copy operation which affects the
clipboard
Note: Do not rename the Edit menu’s “Undo” item, or change the
enabled/disabled state of the Edit menu’s “Undo”, “Cut”, “Copy”,
“Paste”, or “Clear” items if the active window is modeless and it
contains an active editing field. Tools Plus maintains these menu
items automatically. If you are going to make such a change,
preface it by a call to GetFieldString (to retrieve the active
field’s edited text for validation by your application), a call to
SaveFieldString (to save the edited text as the field’s associated
string), then to DeactivateField (to deactivate the window’s
active field and end automatic maintenance of the Edit menu).
Desk Accessories
````````````````
You can give your application the ability to use desk accessories (DAs) by installing the Apple menu. Although desk accessory activity is handled entirely by Tools Plus, your application must adhere to some very strict rules. Your application must have at least two menus to ensure compatibility with System 5 and System 6. The first menu is called “File”, and must contain “Quit” as the last item. The second menu must be the “Edit” menu, as described above. The edit menu must exist as described, even if your application does not support these commands. Lastly, you must ensure that sufficient free space exists in the menu bar to accommodate additional menus, since some DAs create their own menus when running under Finder in System 5 and System 6. Complying with these requirements will ensure that your application is compatible with desk accessories in all system versions.
Desk accessories affect the Edit menu as described later in this chapter in the “Menus and Desk Accessories” section.
For more details about desk accessory interaction, see the PollSystem function.
Menus and Editing Fields
````````````````````````
If your application is going to use editing fields, an “Edit” menu will greatly assist in text editing. The Edit menu automatically performs all text transfer operations between the active editing field and the Clipboard. This includes:
• Cutting the selected text from the active editing field and placing
it on the Clipboard
• Copying the active editing field’s selected text to the Clipboard
• Pasting the Clipboard’s contents into the active editing field
• Undoing the last operation, including the Edit menu’s Cut, Copy,
Paste, and Clear operations, as well as typing and using the Delete
(or Backspace) key
• Undoing the last Undo operation (i.e. Redo)
This functionality is detailed in the “Editing Fields” chapter of this manual.
When a modeless window is activated, or when an editing field is activated on the active window, the Edit menu is automatically updated to reflect the operations that can be performed on the active field. Any editing done within the field automatically updates the Edit menu’s items. If you deactivate a modeless window containing an active editing field, either by closing the window or by activating another modeless window without an active field, all five Edit menu items are disabled.
Opening and closing modal windows does not affect the Edit menu, since menus cannot be accessed while a modal window is active.
Menus and Desk Accessories (Using Finder under System 5 or 6)
This section applies only when your application is running under Finder (not MultiFinder) in System 5 or System 6. Tools Plus automatically maintains menus according to Macintosh User Interface Guidelines (described below).
When a desk accessory is activated, Tools Plus does the following things:
• your application’s menus are memorized so they can be restored to
their original state when your application becomes active again
• all items in your application’s File menu are disabled, except for
the last item, “Quit”
• the Edit menu’s Undo item is renamed to “Undo”. This is done in
view that the item may have read “Undo Typing” or some other
specific action that does not pertain to a desk accessory
• the Edit menu’s “Undo”, “Cut”, “Copy”, “Paste” and “Clear” items
are all enabled for the desk accessory’s use
• all other Edit menu items are disabled
• all other menus in your application are disabled.
When the desk accessory becomes inactive, either by being closed or by activating a window in your application, your application’s menus are restored to their original state.
Menus and Desk Accessories (Using MultiFinder or System 7)
This section applies only when your application is running under MultiFinder (not Finder) in System 5 or System 6, or System 7. When your application is active, its menu bar is displayed. When another application (including System 5 or System 6’s MultiFinder, and System 7’s Finder), or a desk accessory is active, the other application’s menu bar is displayed.
Command Key Equivalents
```````````````````````
Menus can be invoked from the keyboard by setting up a Command key (Command-) equivalent. The character you specify for a Command key equivalent will likely be a letter, however, other characters may be used. When the user holds down the Command key and types a letter, whether in upper or lower case, the equivalent menu item is invoked as if the menu had been pulled down and the required item selected. The appropriate name in the menu bar is highlighted while the operation takes place.
The system responds equally to shifted or non-shifted characters. For example, Command-C and Command-c both invoke the same menu item. Consequentially, Command-+ is read by the system as Command-=. For consistency between applications, upper case letters should be used.
Command-Shift-number combinations are not Command key equivalents, because they are processes as a separate type of event (this is why Command-Shift-1 and 2 eject the internal and external floppy disk). Although unshifted Command-number equivalents can be used, they should be used judicially to avoid confusion.
Note: Several Command key equivalents are reserved for specific
Note: The Macintosh’s Menu Manager has some inherent properties that
Tools Plus cannot override:
• menu items that have submenus cannot have a command key, nor
can they display an SICN icon
• menu items that display an SICN icon cannot have a command
key.
Handling Menus
``````````````
Tools Plus takes care of maintaining the Edit menu when an editing field is active on a modeless window. Use the PollSystem function to constantly inquire about any requests the system may have. When a menu item is selected by the user, either by using the mouse or by typing a Command key equivalent, the corresponding menu name in the menu bar is highlighted and PollSystem reports a doMenu event with the menu number and item number selected by the user. After your application has responded to the selection, call MenuHilite(0) to un-highlight the menu bar.
Hierarchical menus are handled identically to pull-down menus, except when they are selected by the user, the name of their ultimate parent is highlighted in the menu bar. If the user types a Command key equivalent for a hierarchical menu that is not attached to a pull-down menu, PollSystem reports a doKeyDown or doAutoKey event for that keyboard event.
If the Edit menu’s Undo, Cut, Copy, Paste, or Clear are selected while an editing field is active, Tools Plus automatically processes the command and an event is not reported to your application.
If your application does not respond to Apple Events and is running under System 5 or 6’s MultiFinder (not Finder) or System 7, the user can double-click one of your application’s documents while your application is running. This generates a doMenu event that is equivalent to the File menu’s “Open…” item in your application. The user can also select the Special menu’s Restart or Shut Down commands, which generates a doMenu event that is equivalent to the File menu’s “Quit” item, instructing your application to quit.
See the PollSystem function for complete details on the handling of menus.
This procedure creates the Apple menu, inserts an optional “About…” item that is used to invoke your application’s “about box,” and populates the menu with a list of desk accessories. AppleMenu should be called before defining any other menus. If the Apple menu has already been created, AppleMenu does nothing.
AboutName specifies the title of the Apple menu’s “About” item, such as “About my application...” This item is first in the Apple menu, followed by a dividing line, then by the desk accessories listed in alphabetic order. If AboutName is a null string, only the desk accessory names will appear in the Apple menu.
In order to prevent the menu bar from flickering each time a new menu is added, this procedure does not immediately display the Apple menu in the menu bar. When you have finished making changes to the menu bar (by using the Menu and/or RemoveMenu procedures), call UpdateMenuBar to display the changes made to the menu bar. Your application will receive a doMenu event when the user selects the Apple menu’s “About” item.
See “Desk Accessories” at the beginning of Menus for desk accessory menu requirements.
Create a menu (pull-down or hierarchical), add more menu items, or rename existing menu items.
pascal void Menu (short MenuNumber, short ItemNumber,
Boolean EnabledFlag, Str255 MenuText);
procedure Menu (MenuNumber, ItemNumber: INTEGER;
EnabledFlag: BOOLEAN; MenuText: STRING);
When a pull-down menu is first created, the menu’s name (which appears in the menu bar) must be defined first. This is done by calling the Menu procedure with ItemNumber having a value of zero (0). Menu items can then be added to the menu. Your application should define menu items in their correct order (i.e., top to bottom) in order to use the full power of this procedure. A hierarchical menu is created the same way as a pull-down menu, except that you don’t need to create a menu name because hierarchical menus never appear in the menu bar.
MenuNumber specifies the menu number that is affected. The numbers 1 through 15 are reserved for pull-down menus, and the numbers 16 through 200 are reserved for hierarchical menus. Once a menu is created, it is referenced by this menu number. Menu names for pull-down menus are displayed in your application’s menu bar with the Apple menu (if one was created) in the leftmost position, followed by the other pull-down menus in the ascending order of their MenuNumber.
ItemNumber specifies the menu’s item number (from 1 to 255) that is affected. If ItemNumber is zero (0) for a pull-down menu, the Menu procedure refers to the menu’s name in the menu bar. The first two menus (usually File and Edit) are limited to 31 items.
EnabledFlag specifies whether the menu or menu item is enabled or disabled. The menu or menu item can be selected only when enabled. When disabled, the menu or menu item is dimmed and cannot be selected by the user. The two constants that can be used for this purpose are enabled and disabled. If the ItemNumber is zero, the action applies to all items within the specified menu. When the menu later becomes enabled, all items in the menu assume their correct enabling/disabling as specified by your application. Menus and menu items can be enabled and disabled by using the EnableMenu procedure.
MenuText is the menu’s name that appears in the menu bar (if ItemNumber is zero), or the menu item’s name (if ItemNumber is not zero). When a menu item is first created, certain metacharacters are recognized by Tools Plus to provide special instructions to the Menu Manager. You may choose to include or exclude these characters within MenuText, however, you should be aware of their effects. A menu’s name (which appears in the menu bar) should not have any metacharacters. Menu items can include multiple metacharacters.
Note: The Macintosh’s Menu Manager allows only the first 31 items of a
menu to be disabled individually. The entire menu, however, can
always be disabled.
Metacharacters
``````````````
Metacharacters are symbols that tell the Menu Manager to perform special functions on a menu. They are recognized and processed only when a menu item is first created, and are ignored (displayed as ordinary characters) when menu items are renamed. A menu’s name (which appears in the menu bar) should not have any metacharacters. Menu items can include multiple metacharacters or combinations of metacharacters.
Unlike the Macintosh toolbox’s menu routines, Tools Plus removes the semi-colon (;) and Return character ($0D), and does not process them as metacharacters. The following is a list of metacharacters…
^ Display an icon to the left of the menu item. The number following
the caret (^) should be from 1 to 255 (i.e., “^28”). The Menu
Manager adds 256 to the number you state to specify a resource ID
that is in the range of 257 to 511, so if you specify 28, resource
ID 284 is used (28 + 256 = 284). These icon resources are
read from your application.
Tools Plus tries to use a ‘cicn’ icon if Color QuickDraw is
available on the Macintosh running your application. Otherwise, it
will search for an ‘ICON’ (black and white) icon, then an ‘SICN’
icon.
Unlike the equivalent Macintosh toolbox routine, your menu item
will remain unaffected if the specified icon can’t be found
(i.e, empty space is not reserved in the menu).
Be aware that the Menu Manager drawing a ‘cicn’ icon in color
will do so even if the icon was created using 8-bit colors and the
monitor is set to 4-bits. This may produce unsatisfactory results.
If possible, use 4-bit colors or colors that translate well into
4-bit colors.
! Display a special mark to the left of a menu item. The single
character that follows the exclamation mark (!) is displayed. The
check mark is the default. (It is best to use the CheckMenu or
MenuMark procedures.)
< The item is displayed in a special character style. The single
character that follows this symbol specifies the style (Bold,
Italic, Underline, Outline, or Shadow). Multiple styles can be
combined, such as “<B<I” for “bold and italic.” It is best to use
MenuStyle to change styles.
/ The slash (/) indicates that a menu item may be invoked by using a
keyboard equivalent. The single character that follows the slash
specifies the Command key equivalent to a menu item. For
consistency, use upper case letters (shifted characters are
ignored, so Command-+ is interpreted as Command-=). Do not use
Control characters, since older Macintosh keyboards such as those
found on the Macintosh Plus don’t have a Control key.
Tools Plus prevents you from using characters $1B through $1F
(Control-[, Control-\, Control-], Control-Up Arrow, and Control--),
because these characters are reserved by Apple for the system’s
use.
Note: The Macintosh’s Menu Manager has some inherent properties that
Tools Plus cannot override:
• menu items that have submenus cannot have a command key, nor
can they display an SICN icon
• menu items that display an SICN icon cannot have a command
key.
To create a “dividing line” between sections of related menu items, disable the menu item and use ‘-’ (a minus or dash) as the MenuText value. You can use the constant mDividingLine for this purpose.
Special care should be taken to define the menu’s name in the menu bar first, then to define menu items in their correct sequential order. If a pull-down menu item is defined without first defining the menu’s name, the name in the menu bar is automatically defined as “Menu x” where x is the menu number. Also, if any menu items are skipped when defining a menu item (i.e., creating menu item 3 without first creating 1 and 2) the missing menu items (1 and 2) are automatically created as blank, disabled items. Consequentially, metacharacters will not be recognized when the Menu procedure references these automatically created items; the Menu procedure will simply rename the existing item.
A menu’s name (which appears in the menu bar) cannot be changed. If the menu’s name must be changed, the affected menu must be removed with the RemoveMenu procedure, then re-created as required by using the Menu procedure.
In order to prevent the menu bar from flickering each time a new pull-down menu is added, this procedure does not immediately display the new menu in the menu bar. When you have finished making changes to the menu bar (by using the Menu and/or RemoveMenu procedures), call UpdateMenuBar to display the changed menu bar.
Warning: The first two menus (usually File and Edit) are limited to 31
items each. This limit has been imposed to ensure that an
application running under Finder (System 5 and 6) can adhere
Attach a hierarchical menu to a menu item, or detach a hierarchical menu from a menu item.
pascal void AttachMenu (short MenuNumber, short ItemNumber,
short SubMenuNumber);
procedure AttachMenu (MenuNumber, ItemNumber,
SubMenuNumber: INTEGER);
A hierarchical menu can be attached to a pull-down menu or to another hierarchical menu. When attaching a hierarchical menu to a “parent” (or if you prefer to view it the other way, providing a “parent” menu with an “offspring” hierarchical menu), you must specify the parent menu’s menu number and item number, and the submenu’s (offspring) menu number.
You can detach a submenu from its parent in two different ways:
[1] you can state that the “parent menu has no offspring”:
AttachMenu (3, 14, none)
[2] you can state that the “hierarchical menu has no parent”:
AttachMenu (0, 0, 105)
Notice that you can use the constant none to make your code more readable.
MenuNumber specifies the “parent” menu number (from 1 to 15 for pull-down menus, and 16 to 200 for hierarchical menus) to which the hierarchical menu is attached. You can specify zero (0) to detach a parent menu from a known submenu. If the menu number does not exist, AttachMenu does nothing.
ItemNumber specifies the menu item number (from 1 to 255) to which the hierarchical menu is attached. You can specify zero (0) to detach a parent menu from a known submenu. If the menu item does not exist in the specified menu, AttachMenu does nothing.
SubMenuNumber specifies the “offspring” menu number (from 16 to 200) which is attached to the parent menu. You can specify zero (0) to detach a known parent menu from its submenu. If the menu number does not exist, AttachMenu does nothing.
Note: AttachMenu ensures that a hierarchical menu is attached to only
one parent menu item at a time by automatically detaching it from
the old parent menu. Tools Plus will not allow a hierarchical
menu to be attached to itself, or to result in a “cyclical
hierarchy” in which the parent menus eventually lead back to a
submenu. AttachMenu will beep if you attempt to define a cyclical
hierarchy.
Note: When a submenu is attached to a parent menu’s item, that item’s
Command key and “mark” (as defined by MenuMark) are cleared.
Also, if an SICN icon is displayed in the item, it too is cleared.
The Macintosh’s Menu Manager uses these characters to make
